TypeScript Core by chharvey · Pull Request #8861 · WebAssembly/binaryen

chharvey · 2026-06-19T02:09:50Z

The first of several PRs in an attempt to break up #8826 into smaller parts. This PR sets up core typescript functionality and ports over only the top-level types, constants, and enums of the JS API.

Changes:

adds root-level ts/ folder with README.md, package.json, tsconfig.json, and other project files
updates root-level CMakeLists.txt, exporting needed variables & methods (like HEAP8) from Emscripten into the JS build
ts/src/-pre.ts imports the Emscripten-built Binaryen function, calls and awaits it, and exports that as an internal object called BinaryenObj (AssemblyScript calls this object binaryen and exports that publicly).
ts/src/**: the typescript library sits on top of the Emscripten artifact. it accesses the WASM bindings on BinaryenObj imported from -pre.ts.
entrypoint ts/src/binaryen.ts for users, exporting all the parts of the public-facing API. Users use a namespace import instead of a default import:
```
import * as binaryen from "binaryen.ts";
```
(this better aligns with the ES Modules standard since it’s no longer a proper object).
users will still use the same API (binaryen.ExpressionRef, binaryen.i32, binaryen.Module, etc.)
starting some Node.JS tests at ts/tests/. hopefully this will take some of the weight off the python tests

Non-Changes:

original binaryen.js-post.js file has not been touched; the tentative plan is to complete the TS migration before phasing out the JS code (unless decided otherwise by repo maintainers)
python tests also haven’t been touched for now, but maybe a future PR will work on migrating them to Node.JS

API Deprecations (see ts/src/-deprecations.ts for full list; will evolve with more PRs):

enum names have been singularized (e.g. binaryen.Features → binaryen.Feature)
deprecations are still accessible as their old symbols (users can still use binaryen.Features, but there is a doc-comment @deprecated warning for intellisense support)

Get started:

brew install node # includes npm
cd ts/
npm ci          # downloads dependencies
npm run make    # rebuilds out-of-tree into ../build/ and copies the built js to ./build/
npm run check   # runs the python tests
npm run compile # compiles typescript to ./dist/
npm run test    # runs the node tests

See ts/package.json, ts/README.md, and ts/docs/API-Overview.md (in this PR) for details.

MaxGraey · 2026-06-20T21:04:49Z

+    "packageManager": {
+      "name": "npm"
+    }
+  }


Very strange choice. How about simply "version": ">= 20"?

Node.JS has this unusual convention that odd-numbered versions are not stable and become unsupported after 6 months. Only even-numbered versions receive continued long-term support (bugfixes & security updates) after ‘current’ development, which is why i put "^20 || ^22 || ^24 || ^26".

Luckily this is about to change starting in v27 (planned April 2027) where:

Starting with Node.js 27, the release cycle will be annual and every major version will move to LTS status after its six-month Current phase (and six additional months of Alpha phase).

Setting a minimum version is pretty standard practice. You do it once and then forget about it. In your case, though, you'll need to update the list every time a new major node.js version comes out! And why does it matter whether the version is stable or not stable? It doesn't suddenly break anything.

In addition, there are users who rarely update, while others use only the latest version of node (which may not be included in that list).

Fair enough, and agreed, it'd be better to set it once and only update once a version reaches end-of-life. I'll set the minimum to >= 22

MaxGraey · 2026-06-21T20:14:10Z

    target_link_libraries(binaryen_js PRIVATE "-sEXPORT_ES6")
  endif()
-  target_link_libraries(binaryen_js PRIVATE "-sEXPORTED_RUNTIME_METHODS=stringToUTF8OnStack,stringToAscii,getExceptionMessage")
+  target_link_libraries(binaryen_js PRIVATE "-sEXPORTED_RUNTIME_METHODS=out,err,HEAP8,HEAPU8,HEAP32,HEAPU32,stackSave,stackRestore,stackAlloc,UTF8ToString,stringToAscii,stringToUTF8OnStack,getExceptionMessage")


Why we need extended exported symbols? I haven't seen them being used. Also js-bindings works without all of them normally.

Most of these symbols aren't needed in this PR but they will be needed in future code migration (example links below are from #8826):

out will be used in emitAsmJS

i can remove err, looks like it's not used in the TS anywhere

all the heaps are used in various functions, e.g.:

HEAP8 in DataSegment

HEAPU8, HEAP32, & HEAPU32 in emitBinary

stackSave, stackRestore, and stackAlloc will be needed in utilities

UTF8ToString, stringToAscii, and stringToUTF8OnStack for anything using javascript strings (e.g. parseText)

The reason the JS bindings work without them is because the current post.js file is appended to (i think) the WASM bindings before Emscripten processes them; that's the --post-js flag given on line 562. that's why the JS code is able to access the symbols in Emscripten's codebase without being exported. but now that the Emscripten build happens before calling await Binaryen(), we need those symbols exported on the object, so they need to be added to EXPORTED_RUNTIME_METHODS. (see the comment in binaryen_js.d.ts

Can I ask you a question? Are you using Claude to answer me?

No. Sometimes i do use claude/chatgpt to help me understand code i'm not good at (as a javascript/typescript developer with mostly java experience, i have very little c/c++ experience). And i'll use it to bounce ideas off of when writing new code, but i never take its output at face value. Anything i get from AI i will always review first to make sure it's correct. If/when i use LLM output i will be clear in saying so (as an example see my comment here). Claude has been helpful to me in understanding how Binaryen works, but I did not use it in responding to your comments/questions.

Using ';', alot of details, links, structural lists and etc.. these are all signs that you're using claude (exept last message). Honestly, it's not just me who's annoyed by this. highly recommnd read this: https://not-an-llm.bearblog.dev/meat-based-llm-proxies

If you don't experienced in C++/emscripten and delegate everything (including this conversion) to Claude or other LLM I'm curious what value does your contribution actually provide? First of all, what value do you personally get out of this?

i'm being completely honest, everything i'm writing is 100% me. this is just how i write! I like to be explicit and thorough. Semicolons and structured lists make content easier to read as opposed to large blocks of text. I have background in technical writing and content management so that's where i get it from. I don't know how else to convince you.

speaking freely, i'm a little hurt i'm being accused of this. I'm tired of having to dumb down my writing to avoid coming across as AI. All the things that make written content readable and beautiful: em dashes, numbered lists, block quotes, basically all the diverse punctuation available and elements that Markdown has to offer. We have to stop using them? It's f***ing backwards and it sucks.

I put a lot of work into this project, because i believe it has a lot of potential and i want to enhance the development experience for JS/TS devs. Myself being one of them (that's the value I get out of this, to answer your question @MaxGraey). I'm hoping the team won't let all that go to waste.

Hi @chharvey, thanks for your work on this.

@MaxGraey, please keep the conversation here respectful and focused on the content and direction of the PR.

chharvey · 2026-06-22T02:45:27Z

TODO:

package.json: update engines.node and devEngines.runtime.version to ">= 22"
remove err from EXPORTED_RUNTIME_METHODS and accordingly in binaryen_js.d.ts, -pre.ts, & node tests

chharvey added 4 commits June 18, 2026 20:45

build: initialize core files

92905a5

feat: update Emscripten build && test internals

28c2daf

feat: add constants & enums

0f8660d

docs: add overview

97a806d

chharvey requested a review from a team as a code owner June 19, 2026 02:09

chharvey requested review from tlively and removed request for a team June 19, 2026 02:09

MaxGraey reviewed Jun 20, 2026

View reviewed changes

MaxGraey reviewed Jun 21, 2026

View reviewed changes

chharvey added 2 commits June 21, 2026 23:40

refactor: remove out,err from EXPORTED_RUNTIME_METHODS

1ba5226

build: update node version req

7581822

Conversation

chharvey commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chharvey Jun 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MaxGraey Jun 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MaxGraey Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chharvey commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

chharvey commented Jun 19, 2026 •

edited

Loading

chharvey Jun 21, 2026 •

edited

Loading

MaxGraey Jun 21, 2026 •

edited

Loading

MaxGraey Jun 23, 2026 •

edited

Loading

chharvey commented Jun 22, 2026 •

edited

Loading